docs(studies): carousel and pager candidate study - #25

What

Adds docs/studies/carousel-and-pager.md — a candidate study for the "Carousel and existing pager" entry in the widget candidate landscape (#19) — plus its index line in docs/studies/README.md.

Docs only; no code, no syntax reservation, no obligation created for the future ui sub-specification (per the studies charter).

Method

• Primary-source reading of the two references the candidate cites: the APG Carousel pattern and CSS Scroll Snap Level 1 (retrieved 2026-07-20, quotes verified verbatim against the sources).
• Direct verification of the current implementations on main and the feat!: replace Uhura with the 0.4 machine-first language #24 branch, updated to its current head 7f69fc0 (spike catalog contract, ui_catalog vocabulary, the pager primitive adapter and its tests).
• The state-ownership boundary articulated in the feat!: replace Uhura with the 0.4 machine-first language #24 discussion applied as the analysis frame.

Findings the study rests on

• As of 7f69fc0, the pager primitive now dispatches page-change — with a Unit payload, fired on rounded-index crossings during scrolling. The machine learns that the page changed but not which page; the current page itself stays renderer-internal, and no example binds the event on either branch. The position half of the contract — whether, when, and in what vocabulary a program may own the current page — is the open question the study addresses.
• APG defines the semantic-controls half (unconditional prev/next buttons, rotation-control rules) but says nothing about touch, swipe, or reduced motion; Scroll Snap defines resting states and deliberately leaves all kinetics to the UA. Both leave gaps a Uhura contract has to close itself.

Candidate answers (summary)

1. Smallest contract: keyed slides + resting current page (key, not index) + logical axis + required label + indicator token; everything kinetic excluded.
2. Current page: renderer-owned while unobserved; machine-owned (controlled, PageChanged at rest) once anything observes it — the textfield rule applied to paging.
3. Static preview = declared current key, which also gives the pose story for a scrolled viewport.
4. Carousel: composition over pager + button (semantic controls + rotation policy), not a separate Element — conditional on whichever composition tier the ui sub-specification defines.
5. APG baseline features become conformance obligations; reduced motion and non-drag alternatives are named as the places the contract must go beyond the prior art.

Open questions the study cannot decide are listed at the end for the ui sub-specification.

Closes nothing; intended as input for the future ui sub-specification. Feedback welcome — happy to rework or drop per your direction.